TreeGrid Sort Tutorial
1. Sorting rows
Sorting rows according to one ore more columns
-
TreeGrid supports sorting rows by one or more columns ascending or descending.
-
Sort definition
The predefined sort is set by Cfg attribute Sort
as comma separated list of column names.
If the column is sorted descending, it is listed with minus prefix, like "-col1".
There can be set also default column to sort by when there is no predefined sorting or more rows have the same values in all sorting column, it is set Cfg attribute DefaultsSort. It cannot be changed by users.
Sort permitions
-
Cfg attribute
Sorting
='0' disables sorting in grid by users. It can be still changed by API.
-
Cfg attribute
Sorted
='0' temporary disables sorting in grid, but permits users to change the sort columns without resorting the grid.
The Sorted value can be changed by actions SortOff and SortOn.
-
Column can have set its attribute
CanSort
='0' to not let users to sort by this column. It is still possible to do it by API.
-
Row can have set its attribute
CanSort
='0' to not sort its children.
To not sort the root rows set this attribute to Root tag.
It affects every sorting, including API.
-
Sort options
-
Row can be fixed on beginning or end of its parent or root by its
SortPos
attribute. Set it to positive value to fix the row on beginning and negative value to fix it to the end.
There can be more fixed rows on both sides, they are sorted according to their SortPos value.
-
For numbers there are two basic sorting types, number and string sort. The number sort is used by default for column types Int, Float and Date.
You can explicitly choose the number or string sort by column or parent cell attribute NumberSort
.
-
By default are strings sorted formatted according to its Type and Format. To sort them by the direct cell value set column or parent cell attribute
RawSort
='1'. It will speed up the sorting.
-
Enum values are sorted by default by the visible string.
To sort them by key value (EnumKeys) set column or parent cell attribute RawSort='1'.
To sort them by position inside the Enum/EnumKeys set RawSort='2'.
To sort them by index set NumberSort='1'. The Enum values must be set by the index in this case.
-
Column / parent cell attribute
CaseSensitive
to compare the strings case sensitive. By default is on.
-
Column / parent cell attribute
LocalCompare
to compare the strings according to browser's locale settings. By default is off.
It is done only for first 1920 Unicode characters. For higher Unicode characters like Chinese, Korean or Japanese you must define CharCodes instead.
-
Column / parent cell attribute
WhiteChars
as list of characters to ignored when comparing. The strings are compared after these values are removed from them.
-
Column / parent cell attribute
CharCodes
as list of character pairs to replace the first character by the second one in all strings before comparing them. Useful for example to compare strings without punctuation in many languages.
Cell value for sorting
Every cell can have set special value by SortValue
to use it for sorting instead of the cell value.
It can have also different value for descending sorting set by SortDescValue, useful to preserve row position when sorting by the column.
The value can be also dynamically created by JavaScript in API event OnGetSortValue.
-
User interface (<Header>)
Users can change sort settings by clicking to <Header> cell. There can be more headers in grid, the sorting can be individually permitted for them.
-
The header shows sorting icons according to the actual sorting state. The icons can be changed for all columns (if set Header attribute SortIcons='1')
or only for active sorting columns (SortIcons='2').
-
The header can have disabled sorting actions and icons by its SortIcons='0'.
-
All the sorting icons can be reversed (up / down) by Cfg attribute ReversedIcons='1'.
-
There are four possible behaviors for clicking to header cell and sorting icons controlled by Cfg attribute
SortIcons
.
0 - Simple, no icon - Icons are not visible, first click to header sorts ascending, next descending.
1 - Simple - Icons are visible, first click to header sorts ascending, next descending.
2 - Directional, icons only - Only icons can be clicked, top half to sort ascending, bottom half descending.
3 - Directional - The whole header can be clicked, top half to sort ascending, bottom half descending.
-
Sorting actions
It is possible to control how the sorting column will be chosen by users. It can be done by assigning sorting actions to header sort events in Actions tag, for example <Actions OnClickSort='SortAsc OR SortDesc'.
-
Events
There is basic event OnClickSort
called when set Cfg SortIcons to 0 or 1, called for both directions.
Or two events OnClickSortUp
and OnClickSortDown
called when set Cfg SortIcons to 2 or 3, called for the individual direction.
There are the actions with key or button prefixes or their combinations, Right and Middle for mouse buttons and Shift, Alt and Ctrl for control keys.
For example OnShiftRightClickSort or OnCtrlClickSort.
-
Actions
-
SortAsc
, SortDesc
add the clicked column as the first column in sorting. The old columns are shifted to next positions.
If the column is already the first in sorting, it changes its direction if it has different.
If the sorting count reaches MaxSort, the last column is removed.
-
SortAscOne
, SortDescOne
sort only by this column, all old sorting is removed.
-
SortAscAppend
, SortDescAppend
add the column to the end of the sorting.
If the sorting count reaches MaxSort, they do nothing.
If the column is already present in the sorting and has different direction, they changes it.
-
SortAscAdd
, SortDescAdd
add the column to the end of the sorting if there was another click to some column header within last two seconds.
If the sorting count reaches MaxSort, they do nothing.
If the column is already present in the sorting and has different direction, they changes it.
If there was no click to column header within two seconds, it sorts by this column and all old sorting is removed.
-
NoSort
removes the clicked column from sorting.
-
DefaultSort
clears the sorting and restores Sort attribute that was set when the grid was loaded.
-
Auto sort
Row can be automatically sorted to right place when user changes the row value in some sorting column. For this behavior set Cfg attribute AutoSort='1'.
-
API
Before sorting start it is called OnSort API event. It can return true to provide own sorting and not the default one.
After sorting finishes, it is called OnSortFinish API event.
The grid can be re-sorted after some external change by SortRows method.
The individual row can be re-sorted after external change by SortRow method, only if AutoUpdate='1'.
The sorting can be changed by ChangeSort method.